History Rollups

History > History Data > History Rollups

History Rollups

Historical data in the VHS is stored in its raw format. A rollup refers to the process of taking the raw data from the VHS and condensing it using a calculation or by thinning. The VHS uses an iterator to traverse a list of entries in a VHS and "roll" the values up, effectively compressing the data retrieved in a manner indicated by the rollup type chosen. The iterator is used by several applications in CygNet Software, including:

visualizing data on a CygNet Trend Tool in CygNet Studio (See Editing a Series)
visualizing aggregated data on a Default Trend
presenting aggregated data in summary nodes in the Group service
presenting data in the Group Grid in CygNet Studio (see Columns)
display station and group levels rollups in CygNet Measurement clients
viewing rolled up forecasted gas load values for a meter group in Energy Load Forecasting
display rollups in nodes in the General Contract Monitor
retrieving data for CygNet Business Operations (using the Business Object Builder)
supported in CygNet Native Operations (History and Point)
exporting history data with CygNet Excel Export
exporting history data with the CygNet History Export Utility
writing ODBC queries via the HistoryRollup stored procedure
scripting rollups using CxVhsClient and CxVhsLib.RollupIterator and CxVhs.VhsDatastoreInterface
scripting tag rollups in the CxGrpGrid

Also refer to CygNet.API.Historian.Client (GetDailyRollup, GetHourlyRollup, GetHistoricalRollup, HistoricalRollupEnumerable) and CygNet.Data.Historian.HistoricalEntry (HistoricalRollupType Enumeration, HistoricalRollupUnit Enumeration) in the CygNet.API.chm Help file for CygNet.API .NET usage.

Also see Notes about History Rollup for information and examples about rollups.

Rollup Parameters

There are several required parameters that must be passed to the rollup iterator when configuring rollups, either via UI configuration or script. In some applications the parameter's name is slightly different, depending on the user or script interface being used, and is noted in the table below.

Parameter Names	Description
Rollup Period rollupPeriod RollupPeriod	Specifies the time interval by which a rollup type takes place. The rollup period refers to the quantity of units in a period. For example, to rollup 30 days, the RollupPeriod is 30 and the RollupUnit is "days."
Rollup Type rollupType RollupType	Specifies the type by which to roll up data for a selected point. The possible values are listed in CxRollupType or in CygNet.Data.Historian.HistoricalRollupType. See Rollup Type below.
Rollup Units rollupUnits RollupUnits	Specifies the time units by which a rollup takes place. This refers to time increments, such as seconds, minutes, hours, or days. The possible values are listed in CxRollupUnits or in CygNet.Data.Historian.HistoricalRollupUnit.
Tag TagString	The point tag from which data is being retrieved in valid CygNet tag string format.
Earliest Time earliestTime EarliestTime StartTime TimeStampEarliest	The starting date and time of the retrieval period, or how far back to go for data. The date range can be specific or you can use date wildcards. See Rules of EarliestTime and LatestTime for more information.
EndTime Latest Time latestTime LatestTime TimeStampLatest	The ending date and time of the retrieval period, or the most recent date. The date range can be specific or you can use date wildcards. See Rules of EarliestTime and LatestTime for more information.
Top of SubUnit Top of Sub-Unit TopOfDayHour TopOfSubUnit TopSubUnit topSubUnit	The offset value to use if the subunit to the major unit does not start at the time unit expected. Subunit means whatever unit of time is the next smaller than that defined in RollupUnits.(i.e. hours to a day, minutes to an hour). This provides a method to allow for differences in start of day, time zone, or scheduling. For example, to accommodate contract days starting at 5 AM, the TopOfDayHour would be 5 (indicating 5 hours from midnight). See Offset Notes for more information.
Historian.Name VHS Site.Service VhsSiteService	The site and service name of the VHS point tag, in "site.service" format.

Parameter Names

Description

Rollup Period

rollupPeriod

RollupPeriod

Specifies the time interval by which a rollup type takes place. The rollup period refers to the quantity of units in a period. For example, to rollup 30 days, the RollupPeriod is 30 and the RollupUnit is "days."

Rollup Type

rollupType

RollupType

Specifies the type by which to roll up data for a selected point. The possible values are listed in CxRollupType or in CygNet.Data.Historian.HistoricalRollupType.

See Rollup Type below.

Rollup Units

rollupUnits

RollupUnits

Specifies the time units by which a rollup takes place. This refers to time increments, such as seconds, minutes, hours, or days. The possible values are listed in CxRollupUnits or in CygNet.Data.Historian.HistoricalRollupUnit.

Tag

TagString

The point tag from which data is being retrieved in valid CygNet tag string format.

Earliest Time

earliestTime

EarliestTime

StartTime

TimeStampEarliest

The starting date and time of the retrieval period, or how far back to go for data. The date range can be specific or you can use date wildcards.

See Rules of EarliestTime and LatestTime for more information.

EndTime

Latest Time

latestTime

LatestTime

TimeStampLatest

The ending date and time of the retrieval period, or the most recent date. The date range can be specific or you can use date wildcards.

See Rules of EarliestTime and LatestTime for more information.

Top of SubUnit

Top of Sub-Unit

TopOfDayHour

TopOfSubUnit

TopSubUnit

topSubUnit

The offset value to use if the subunit to the major unit does not start at the time unit expected. Subunit means whatever unit of time is the next smaller than that defined in RollupUnits.(i.e. hours to a day, minutes to an hour). This provides a method to allow for differences in start of day, time zone, or scheduling.

For example, to accommodate contract days starting at 5 AM, the TopOfDayHour would be 5 (indicating 5 hours from midnight).

See Offset Notes for more information.

Historian.Name

VHS Site.Service

VhsSiteService

The site and service name of the VHS point tag, in "site.service" format.

Rollup Type

The following table describes the rollup types that are supported by CygNet. Points with blank values, non-numeric values (for example, string value = "BOB"), and pseudo-numeric values (for example, enumerated value = "1:ENABLED") are handled differently for each rollup type. The last four columns of the table describe how the VHS uses these history values when returning data for each rollup type.

Rollup Type	Description	Value is Used If...
Rollup Type	Description	Numeric	Blank	Non-Numeric	Pseudo-Numeric
Raw Data	Returns raw data from the VHS.
Calculated Weighted Average	Returns a time-weighted rolling average for the range with a timestamp that reflects the end of the rollup interval. For example, if the data window is a three-day period and the rollup interval is one day, the result would be one value per day that represents a time-weighted average for the three-day period.	(calculated)			Uses numeric portion of value to calculate weighted average
Calculated Mean	Returns a simple average of the values for the range with a timestamp that reflects the end of the rollup interval.	(calculated)			Uses numeric portion of value to calculate mean
Calculated Min	Returns the minimum value for the range with a timestamp that reflects the end of the rollup interval.	(calculated)			Uses numeric portion of value to calculate minimum
Calculated Max	Returns the maximum value for the range with a timestamp that reflects the end of the rollup interval.	(calculated)			Uses numeric portion of value to calculate maximum
Calculated Delta	Returns the difference between the minimum and maximum values for the range. If there is no difference, the returned value is zero.	(calculated)			Uses numeric portion of value to calculate delta
Calculated Last	Returns the last value received for the range.				(last)
Thin Median	Returns the middle value from the set of values for the range. If there is an even number of values collected, the value returned is the one that falls before the true middle. If no values are collected, no values are returned. See Thin Rollup Types for more information.	(middle)			(middle)
Thin Min/Max	Returns the minimum and maximum values for the range. If only one value is collected, it returns the value. If no values are collected, no values are returned.	(min and max)			(numeric portion)
Thin Last	Returns the last value collected for the range. If no values are collected, no values are returned.	(last)			(last)

About Timestamps and Rollups

The timestamp for a Calculated Rollup is the timestamp for the end of the rollup interval.

The timestamp for a Thinned Rollup is the value’s actual timestamp. Since the timestamp for a thinned rollup is the value’s actual timestamp, the timestamp may be outside of the data window if the value occurred before the period. For example, the value hasn’t changed for two days. Even though the data window is only the current day, the timestamp of the value would be from two days ago.

If a change is detected in a history point version, the VHS forces a recalculation of the rollup, eliminating possible "stale" history data in a rollup. The rollup recalculation is triggered for a history point when either the history point version has changed, or the VHS startup timestamp has changed.

History Rollups Dialog Box Scripting

The following scripting options are available for data interface functions related to the History Rollups dialog box.

COM API	Description and Link
CxDialogs CxScript	The ShowRollupConfigDialog method displays the History Rollup Configuration dialog box. See CxDialogs.ShowRollupConfigDialog for more information. See CxScript.GlobalFunctions.ShowRollupConfigDialog for more information.

COM API

Description and Link

CxDialogs

CxScript

The ShowRollupConfigDialog method displays the History Rollup Configuration dialog box.

See CxDialogs.ShowRollupConfigDialog for more information.
See CxScript.GlobalFunctions.ShowRollupConfigDialog for more information.